home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 426-450 / disk_426 / conman / extras.doc < prev    next >
Text File  |  1992-05-06  |  4KB  |  88 lines
  1. This file describes the auxiliary commands History, Push, Queue, and 
  2. Dropbuf supplied with Conman.
  3.  
  4.                              -- History --
  5. History is a command utility to save, load, or display the history buffer.
  6. It is useful for saving and then preloading a set of commands for working
  7. on a particular project, or just to review your current command history.
  8. History works only from a CLI or other shell and requires version 1.1 or
  9. later of ConMan.
  10.  
  11. Usage.
  12. The usage template for history looks like
  13.                    history [>savefile] [inputfile]
  14.  
  15. If you don't specify any options, the command displays the current buffer 
  16. on the standard output stream.  You can redirect this output into a file 
  17. to save it (or perhaps edit it).
  18.  
  19. If you specify a filename argument after the command, History will load
  20. the contents of that file into the history buffer.  The new lines are 
  21. loaded just as though they had been typed in.  You can use the CTRL-B key
  22. to clear the buffer first if you don't want to keep the current commands.
  23.  
  24. The lines to be loaded into the history buffer should have been obtained
  25. by capturing a previous session.  If you try something silly like loading 
  26. an executable file into the buffer, nothing will break, but you'll end
  27. up with a lot of funny-looking characters in the command history.
  28.  
  29. Errors.
  30. History checks to be sure that you've run it from a command shell that 
  31. uses ConMan, since the history is maintained by ConMan.  If you try it
  32. from another environment, it reports "Not a ConMan console window" and
  33. exits.
  34.  
  35.  
  36.                      -- Push, Queue, and Dropbuf --
  37. ConMan provides special capabilities that allow an input stream to be 
  38. used as a temporary "scratchpad" to store a series of data lines.  These
  39. lines can be "stacked" (last in, first out) or "queued" (first in, 
  40. first out) to be read at a later time.  These special capabilities are 
  41. available through the command utilities Push, Queue, and Dropbuf.  Here's
  42. what they do:
  43.  
  44. Push takes its command line and "stacks" it in the input stream.  Stacked
  45. lines always go the the head of the internal buffer, and are then available 
  46. for the next program (or the CLI) that reads from the stream.  For example,
  47. entering "push echo hi" would result in 
  48.  
  49. 1> push echo hi
  50. 1> hi
  51. 1>
  52.  
  53. The command line can be surrounded by double-quotes to prevent the CLI
  54. from breaking it; the quotes are stripped off before the line is actually
  55. stacked.  Push is useful within an "execute" script to allow a series of
  56. responses to be prepared for a program.  For example, suppose that the
  57. program "myprog" expects three lines of input.  Then the following script
  58. could be used to launch the program:
  59.  
  60. ; Launch "myprog" with prepared data
  61. push data line 3
  62. push data line 2
  63. push data line 1
  64. df1:c/myprog -t
  65.  
  66. Note that the command lines are stacked in reverse order (well, in normal
  67. order if you're a Forth programmer).
  68.  
  69. The Queue command behaves just like the Push command, except that it 
  70. places the data in "first in, first out" order.  New data is placed behind
  71. all previously queued (or stacked) data.  The choice of whether to use 
  72. PUSH or QUEUE is usually just a matter of convenience, unless the data is
  73. available in a particular order that constrains the decision.
  74.  
  75. Data lines entered by Push or Queue are never displayed on the console,
  76. and are always ahead of any data received through the input stream.
  77.  
  78. Sometimes it may be necessary to delete or purge previously stacked data.
  79. For example, if a program aborted after reading only part of its prepared
  80. input stream, it would be confusing (or dangerous!) for the stacked data
  81. to be read from the command stream.  The Dropbuf command is provided to 
  82. "drop" (delete) all stacked or queued data, without perturbing any of the
  83. lines received through the input stream.  
  84.  
  85. Two brief demonstration scripts, "pushdemo" and "dropdemo", have been
  86. included as examples.  Type them out and then try "execute pushdemo".
  87.  
  88.